API Reference (PlanningSpace version: 16.5 Update 33 (16.5.33))
Important: For correct API reference information, you should ensure that the version of this document matches with the version of your PlanningSpace server. See the version number in the heading and 'Software version' in every page footer.
The topics in this section contain API reference information for the APIs which provide access to data and application functions:
- Dataflow Web API
- Economics Web API
- Financials Web API
- PalantirCash OData API
- Economics Calculation API (only available in version 16.5 Update 10 and later)
Note: Integration Services (OData) API requests provide access only to the '/data' resources of these APIs. The PalantirCash API offers only data resources and no access to application functions.
Two more APIs provide administration functionality:
- PlanningSpace Web API
- IPS Server Monitor Tenant API
For version 16.5 Update 13 and later: The Server Monitor Tenant API can be disabled using the IPS service setting 'Enable Server Monitor'. When disabled, all back-end data collection and API endpoints are stopped; and the Server Monitor user interfaces in IPS Manager and PlanningSpace are removed.
Authorization
Authorization to use API resources is determined by the user account that has been used to authenticate the Web API session, or Integration Services API request. When a user account does not have authorization to use an API resource, the API server will send a '403 Forbidden' response. The user account must be a member of a tenant workgroup that is assigned access to the tenant role which governs the API resource; for example the 'Security' role governs access to all user management functions, and this is normally only granted to members of the 'Administrators' workgroup. Administrators can perform user management via the PlanningSpace API, and modify user accounts and workgroups.
Integration Services API requests are only authorized for '/data' API resources, even where the user account has additional degrees of access.
The IPS Server Monitor Tenant API is accessible for all user accounts.
For general information about workgroups and roles, see the PlanningSpace Deployment Guide.
HTTP methods used by the Web API
The Web API implements the following HTTP methods for its operations, based on the conventions for RESTful API design:
| Method | Description |
|---|---|
| GET | Retrieves a resource. |
| POST | Creates a new resource or performs an action on the specified resource. |
| PATCH | Performs a partial update on an existing resource (that is, only changes are sent in the API request). |
| DELETE | Deletes a resource. |
GET requests for users, workgroups and roles (and using the 'include' query)
In the PlanningSpace API, the '/api/v1/users', '/api/v1/roles' and '/api/v1/workgroups' API resources omit information by default. The contents of 'userWorkgroups', 'users', 'allowedRoles', etc. are not included in the response.
This can be modified by:
- using the 'include' query, for example
/api/v1/users?include=userWorkgroups,/api/v1/workgroups?include=users,allowedroles,deniedroles - using the '$select' query, for example
/api/v1/users?$select=userWorkgroups,/api/v1/users?$select=id,userworkgroups
How to use the API Reference
Click the API name in the left-hand menu (under 'API Reference') to display its API resource groups and operations. Alternatively, use the topic links below.